package XPathProj;

import java.io.IOException;

import javax.xml.namespace.QName;
import org.w3c.dom.Node;
import javax.xml.xpath.XPathExpressionException;

import org.xml.sax.SAXException;

/**
 * 
 * @author Amiad
 * This interface is for the first step of a project on course 89-281 in Bar-Ilan University.
 * The class will load an XML file and will be able to give a correct XPath 1.0 answer.
 *
 */
public abstract class XPathProject {

	/**
	 * This function will load the XML file.
	 * @param fileLocation - a string representing the location of the XML file.
	 * @throws SAXException - If any parse errors occur.
	 * @throws IOException - If any IO errors occur.
	 * @throws IllegalArgumentException - When fileLocation is null
	 */
	public abstract void loadXML(String fileLocation) throws SAXException,
													IOException,
													IllegalArgumentException;
	
	/**
	 * Evaluate an XPath expression in the context of the specified Node
	 *  and return the result as the specified type.
	 * If returnType is not one of the types defined in XPathConstants ( NUMBER, STRING, BOOLEAN, NODE or NODESET) 
	 *  then an IllegalArgumentException is thrown.
	 * If a null value is provided for source, the root of the document will be used for the context.
	 *  If expression or returnType is null, then a NullPointerException is thrown.
	 *  
	 * @param expression - The XPath expression.
	 * @param source - The starting context.
	 * @param returnType - The desired return type.
	 * @return Result of evaluating an XPath expression as an Object of returnType.
	 * @throws XPathExpressionException - If expression cannot be evaluated. 
	 * @throws IllegalArgumentException - If returnType is not one of the types defined in XPathConstants. 
	 * @throws NullPointerException - If expression or returnType is null.
	 */
	public Object evaluate(String expression, Node source, QName returnType)
            				throws XPathExpressionException,
            						IllegalArgumentException,
            						NullPointerException {
		return evaluate(expression, returnType);
	}
	
	/**
	 * Evaluate an XPath expression in the context of the root of the document
	 *  and return the result as the specified type.
	 * If returnType is not one of the types defined in XPathConstants ( NUMBER, STRING, BOOLEAN, NODE or NODESET) 
	 *  then an IllegalArgumentException is thrown.
	 *  
	 * @param expression - The XPath expression.
	 * @param returnType - The desired return type.
	 * @return Result of evaluating an XPath expression as an Object of returnType.
	 * @throws XPathExpressionException - If expression cannot be evaluated. 
	 * @throws IllegalArgumentException - If returnType is not one of the types defined in XPathConstants. 
	 * @throws NullPointerException - If expression or returnType is null.
	 */
	public abstract Object evaluate(String expression, QName returnType)
            				throws XPathExpressionException,
    								IllegalArgumentException,
    								NullPointerException;
}

